Dink table reference

In DinkLua, just about every DinkC-equivalent engine feature is stored in the "dink" table, with everything else that isn't instead listed somewhere in the object reference or guide. I didn't want to write this, as trial and error is part of the fun, but too many people nagged.

As of v0.94 of YeOldeDink, many features have been moved to the global objects described in the separate object reference, and most mathematical equivalents are available built into Lua as described in the relevant section below.



Inventory

Functions that deal with the inventory.

dink.add_item(string script, int seq, int frame) adds an item to the inventory with script of script, and sequence of seq and frame of frame to display to the player.

dink.add_magic(string script, int seq, int frame) as above, except adds it to one of the 8 magic slots instead.

dink.kill_this_item(string script) removes the item with the corresponding script from the inventory by running drop(). Will run holdingdrop() and disarm() if currently in use, and then redraw the status bar.

dink.kill_this_magic(string script) as above for magic.

dink.free_items() returns the amount of free item slots remaining in the normal inventory.

dink.free_magic() as above, but for magic instead.

dink.kill_cur_item() runs disarm(), holdingdrop(), and drop() of the currently-equipped item and halts the script.

dink.kill_cur_magic() same as above except for magic.

dink.arm_weapon() runs disarm() then arm() of the currently-equipped weapon.

dink.arm_magic() the same as above for magic.

dink.count_item(string script) returns the amount of items in the inventory that have the script "script".

dink.count_magic(string script) same for magic.

dink.get_item(string script) returns the inventory slot number of the item with the specified script

dink.get_magic(string script) as above for magic.

Status bar and interface

dink.show_inventory() will cause the inventory to be displayed, like it would if one were to press the Enter key.

dink.set_keep_mouse(bool) determines if the mouse cursor should still be active when game mode is changed to 2/3 (on).

dink.draw_status() re-draws the status bar. Interrupts any health or gold updates etc.

dink.stop_entire_game() halts everything while a choice menu is active. Does not halt script timers and whatnot. Mainly used for the level up choice menu.

dink.set_mode(int mode) sets the game mode, which may be 0, 1, 2, or 3. Mode zero is when the engine is initted or restarted, after which mode 1 is automatically applied (mouse mode). Mode 3 is main mode with status bar and such, automatically applied after setting mode 2.

Audio and Multimedia

Background music, sound effects, and video.

dink.playavi(string movie) will play movie with path relative to dmoddir if ffmpeg's ffplay is installed and available.

dink.playmidi(string music_file, int fadein) plays music_file (relative to SOUND in dmoddir) with an optional fade-in time in milliseconds, assuming the filetype is supported. More musical features are listed in the object reference.

dink.playsound(int sound_number, int min_speed, int rand_speed_to_add, sprite, bool repeat_p) plays sound effect in slot "sound_number" and returns a sound object. Please see the guide and object reference for more information. Everything apart from sound_number is optional.

dink.load_sound(string wav_file, int slot) attempts to load wav_file (path relative to dmoddir's SOUND) into the specified slot, of which there are 200.

dink.kill_all_sounds() only halts sounds set looping with "survive".

dink.actually_kill_all_sounds() will halt all playing sound effects.

dink.stopmidi() stops the currently-playing background music.

dink.turn_midi_off() switches off background music playback entirely.

dink.turn_midi_on() switches it back on.

dink.loopmidi(bool loop_midi) determines if background music will loop indefinitely or not. Only takes effect the next time music is played. Equivalent to setting music.loop.

dink.set_music_vol(int volume) sets the currently-playing music's volume, which may be between zero and 128.

Text

Fonts and displayed text. Sprite text is covered in the object reference.

dink.initfont(string fontname) replaces the text TTF with fontname. In YeOldeDink, the font will be searched for in system fonts, or in Fontconfig, or in the root of dmoddir. This may be operating system-dependent and will not work with the alt text feature enabled.

dink.set_font_color(int index, int r, int g, int b) sets specified text colour index (1 to 15) with the corresponding RGB values between 0 and 255.

dink.say_xy(string text, int x, int y) displays text at the specified co-ordinates, with an x offset of 300 or so. Also returns a sprite object.

dink.say_stop_xy(string text, int x, int y) as above but interrupts the script until dismissed or some time has passed. Does not return a sprite object!

Scripting

Things that relate to the scripting engine.

dink.set_callback_random(string func, int min, int max) - runs function "func" in the current script after a random interval between min and max +min in milliseconds. Also returns a callback index that may later be murdered manually.

dink.wait(int delayms) pauses the execution of the script for at least the amount specified by delayms in milliseconds, after which it is resumed. May overshoot by a little bit or a lot.

dink.script_attach(int sprite) assigns the current script a different owner sprite. Common values are zero (the screen), and 1000 (persistent across screens) when not a living sprite.

dink.callback_kill(int slot) nullifies the specified callback slot for a script set to wait and resumes its execution, or terminates a random callback.

dink.spawn(string script) activates an instance of script "script" persistently attached to fake sprite 1000. The script may also be a .c assuming the backend is enabled. Returns the slot number the script was loaded into.

dink.kill_this_task() halts the currently-executing script.

dink.run_script_by_number(int script, string function) will run a script's specified function that has already been loaded into a slot.

Loading and Saving

Saved games and serialisation etc.

dink.save_game(int slot) makes a standard save in the specified save slot.

dink.load_game(int slot) attempts to load the game from the specified slot.

dink.set_save_game_info(string info) overwrites the line in saves with "info".

dink.reset_timer() resets the amount of minutes indicated in savefiles back to zero.

dink.todisk(variable, string filename) will serialise a table or other variable to the specified filename in the root of dmoddir.

dink.fromdisk(string filename) returns your variable from the file. Should return nil if it doesn't exist.

dink.copy_to_clipboard(string clipboard_info) will copy a string to the clipboard, such as a high score, or debug information.

dink.game_exist(int slot) returns a bool indicating if the save slot is in use or not.

Utility

Information for the scripter, and other things for dealing with the inner workings of the engine.

dink.lock_screen() will lock the screen with the usual borders and prevent the player from walking onto any neighbouring ones.

dink.unlock_screen() undoes the above.

dink.is_screen_locked() returns a bool indicating the screen's locked status.

dink.show_console() will enable the debug interface and the scripting consoles.

dink.restart_game() kills off all sprites, halts all repeating sounds and scripts, sets mode and screenlock to zero (runs "start" script), resets the save data, hitmap, and button input, and resets all DinkC variables. Might also reset the volatile table in 0.95 and later.

dink.debug(string message) writes message to the debug log, accessible from the debug menu in YeOldeDink, as well as to debug.txt in dmoddir if started with debug mode on (-d flag), also visible on the command line on certain platforms, and the JavaScript console in the browser.

dink.get_version() returns 108.

dink.get_client_fork() returns 3 in YeOldeDink.

dink.get_fps() returns the amount of frames per second, roughly.

dink.get_platform() returns zero on Windows, 2 on macOS, 3 on GNU/Linux, and -1 otherwise.

dink.get_last_sprite() returns the number of the most recently created sprite, for checking how many living sprites there are. Does not return a sprite object.

dink.kill_game() Exits the program in an extremely violent manner.

dink.scripts_used() returns the amount of script slots being used across all backends.

dink.var_used() returns how many DinkC variables (accessed with "global") are in use at the time of invocation.

dink.get_truecolor() returns a bool indicating if the user launched with 24-bit graphics mode enabled.

Graphical

Frames, sequences, BMPs, and dink.ini.

dink.show_bmp(string bmp_name, bool show_marker) displays bmp_name with an optional flashing thingy indicating which screen you're on as per show_marker. Path for BMP (or PNG etc) is from root of dmoddir.

dink.copy_bmp_to_screen(string bmp_name) blits bmp_name onto the background layer containing the tiles and background sprites. Can also be a PNG or something.

dink.init(string iniline) parses a dink.ini line.

dink.preload_seq(int sequence) loads the specified sequence into RAM so it is displayed faster.

dink.load_palette(string bmp_file) updates the 256-colour palette according to what's in bmp_file. Path is relative to root of dmoddir. Also usable in 24-bit mode for filling the screen with different colours.

dink.fill_screen(int palette_index) draws over the background layer with the specified palette index. Will work in both 8-bit and 24-bit display modes.

dink.get_seq_box(int seq, int frame) returns four parameters corresponding to the bounding box of the specified sequence and frame (left, right, top, bottom).

dink.get_seq_offset(int seq, int frame) returns two parameters corresponding to the X and Y offset ("depth dot") of the specified sequence and frame.

dink.get_seq_hbox(int seq, int frame) returns four parameters corresponding to the dink.ini "hardbox" of the specified sequence and frame (left, right, top, bottom).

Contrary to the DinkC reference, the palette is in fact stored in save files.

Buttons and input

dink.wait_for_button() waits for a button press. Button keycode is stored in the "result" global variable.

dink.stop_wait_for_button() stops the above.

dink.activate_bow() activates the bow, sets the player sprite's pseq to 100 + direction.

dink.push_active(bool can_push) determines if the player sprite may push against something.

dink.set_button(int button, int function) doesn't do anything in YeOldeDink. Joystick settings are set from the menus, and a key script bound to a controller button is set from dink.ini.

dink.is_controller_present() returns a bool indicating if a controller/joystick is connected.

dink.rumble_controller(intensity1, intensity2, duration) will vibrate the controller for duration ms, with intensity for high and low motors being between zero and 65535.

Sprites

dink.disable_all_sprites() sets the "disabled" property of all living sprites to true. In this state, the sprites will not be updated.

dink.enable_all_sprites() does the opposite to above.

dink.create_sprite(int x, int y, int brain, int sequence, int frame) creates a sprites with the specified parameters and returns a sprite object. More details are available in the object reference.

dink.get_sprite(int sprite) returns a sprite object from a sprite number.

dink.get_sprite_with_this_brain(brain, sprite_ignore) sprite_ignore may be a sprite object. Returns the first sprite object that has the specified brain.

dink.get_rand_sprite_with_this_brain(brain, sprite_ignore) same as above except picks randomly.

dink.set_dink_base_push(int base_sequence) sets the push sequence for the player sprite. More easily set by using player.base_push.

dink.set_smooth_follow(int smooth) determines if sprites will follow another using all 8 directions and a different algorithm. Set to 1 to switch on. Off by default, which uses the old <=1.07 algo.

dink.get_next_sprite_with_this_brain(int brain, int sprite_ignore, int starting_sprite) Loops over all sprites starting with starting_sprite, and finds the next one with the specified brain while ignoring a specified sprite if not set nil.

dink.add_exp(int exp, sprite sprite) adds exp amount of experience points to a sprite object with a text indicator. Useful for sidequests etc.

dink.get_last_sprite() will return the number of the most recently created sprite. Might be helpful to see if you're pushing against the sprite limit. Will have to be manually turned into a sprite object with dink.get_sprite().

Screen, collision data, and tiles

dink.draw_hard_map() redraws the screen's collision data, and updates editor sprites with their override information.

dink.load_screen(int screen) loads a screen in map.dat according to its dink.dat index value. Also updates the screen timer, and the show_bmp indicator flasher.

dink.draw_screen() redraws the screen. returns true if successful.

dink.draw_background() re-draws the background layer of the screen containing the tiles, and clear off any blood etc.

dink.inside_box(int x, int y, int left, int right, int top, int bottom) returns a bool indicating if the specified X/Y co-ordinates are within the box specified by left, right, top and bottom.

dink.map_hard_tile(int tile_position, int hard_tile_index) updates one of the 96 alt_hard tiles with one of the 800 tiles in hard.dat.

dink.map_tile(int tile_position, int tile_index) updates one of the 96 screen tiles with one of the 7808 tilescreen tiles.

dink.load_tile(string tilescreen, int tilescreen_index) overwrites one of the 61 tilescreen indices with another tilescreen BMP or PNG. Path starts in TILES in dmoddir. The first 41 will be saved in the save file.

dink.load_map(string mapdat, string dinkdat) replaces the current map file with the specified filenames. Path is relative to root of dmoddir.

dink.fade_down() fades down the screen over a period of 1 second or thereabouts, and pauses the script until completed. White pixels are still visible.

dink.fade_up() fades up the screen if faded down.

dink.clear_editor_info() clears all editor sprite overrides such as barrels and burnt trees while resetting their timers.

Numbers, date, and time

A whole bunch of mathematical functions are included in Lua's inbuilt math library that replace many DinkC features such as "math_abs". The Lua Manual contains a full list of them. Floating point numbers that you want used by the engine must be converted to an integer with math.tointeger() or math.floor(), or lume.round().

dink.get_time_real() returns an integer indicating the current time of the day quantified in minutes. Lua also contains time-related features built in.

dink.get_time_game() returns the amount of minutes of the user's current session as stored in the save file after being added to the difference between the start time and the current time. The start time is reset upon saving meaning it only reliably determines how long it has been since the player last saved.

dink.get_date_year(), get_date_month, get_date_day return an integer containing year, month, or day of month.

dink.random(int range, int base) return a random number between base, and base + range -1.

It is preferable to use Lua's math.random() for more intuitive random number generation. math.random(3) will return 1, 2, or 3. math.random(5, 6) will return either 5 or 6.

Other/weird

dink.force_vision() doesn't do anything and never will.

dink.get_burn() returns 1

dink.get_last_bow_power() returns the power of the last bow shot, which is the amount of time in milliseconds it was activated up to about 500 or so.

dink.stopcd() displays a funny message.